Chip 1996 November/Chip 11-96.iso/workshop/howto/nis

Text File | 1996-05-25 | 20KB | 535 lines

The Linux NIS(YP)/NIS+/NYS HOWTO
by Andrea Dell'Amico <[e-mail]>,
   Mitchum DSouza    <[e-mail]>,
   Erwin Embsen      <[e-mail]>
Version 0.2, Last Modified on June 16, 1994


CONTENTS

  0. Glossay of Terms
     0.1. Some General Information

  1. Introduction
     1.1. New versions of this document
     1.2. Disclaimer
     1.3. Feedback
     1.4. Acknowledgements

  2. NIS or NIS+ (aka. NYS) ?

  3. How it works

  4. What you need to set up NIS?

     4.1. The RPC Portmapper
     4.2. Determine whether you are a Server, Slave or Client.
     4.3. The Software
     4.4. Setting up a NIS Client

  5. What you need to set up NYS (NIS+)?

     5.1. Determine whether you are a Server, Slave or Client.
     5.2. The Software
     5.3. Setting up a NYS Client
     5.4. The nsswitch.conf File

  6. Setting up a NYS server

  7. Verifying the NIS Installation

  8. Common Problems and Troubleshooting NIS

  9. Frequently Asked Questions



0. Glossary of Terms

In this document a lot of acronyms are used. Here are the most
important acronyms and a brief explanation:

    DBM      DataBase Management, a library of functions which
             maintain key/content pairs in a data base.

    DLL      Dynamically Linked Library, a library linked to an
             executable program at run-time.

    FTP      File Transfer Protocol, a protocol used to transfer
             files between two computers.

    NIS      Network Information Service, a service that provides
             information, that has to be known throughout the network,
             to all machines on the network.

    nsl      network services library, a library of network service
             calls (socket, bind, etc...) on SYSV Unixes.

    NYS      This is a mutation of the word NIS and represents the NIS+
             services library written by Peter Eriksson <[e-mail]>.

    RPC      Remote Procedure Call. RPC routines allow C programs to
             make procedure calls on other machines across the network.

    YP       Yellow Pages(tm), a registered trademark in the UK of
             British Telecom plc.

    TCP/IP   Transmission Control Protocol/Internet Protocol. It's a
             data communication protocol often used on Unix machines.


0.1. Some General Information

The next three lines are quoted from the Sun(tm) System & Network
Administration Manual:

    "NIS was formerly known as Sun Yellow Pages (YP) but
     the name Yellow Pages(tm) is a registered trademark
     in the United Kingdom of British Telecom plc and may
     not be used without permission."

NIS stands for Network Information Service. It's purpose is to
provide information, that has to be known throughout the network,
to all machines on the network. Information likely to be
distributed by NIS is:

    - login names/passwords/home directories (/etc/passwd)
    - group information (/etc/group)

So, for example, if your password entry is recorded in the NIS
passwd database, you will be able to login on all machines on the
net which have the NIS client programs running.

Sun is a trademark of Sun Microsystems, Inc. licensed to
SunSoft, Inc.


1. Introduction

More and more, Linux machines are installed as part of a network of
computers. To simplify network administration, most networks (mostly
Sun-based networks) run the Network Information Service. Linux machines
can take full advantage of existing NIS service or provide NIS service
themselves.
This document tries to answer questions about setting up
NIS(YP)/NIS+/NYS on your Linux machine. Don't forget to read
section 4.1, The RPC Portmapper.


1.1. New versions of this document

New versions of this document will be posted periodically (about every
month) to the newsgroups comp.os.linux.announce and comp.os.linux.misc.
The document is archived on a number of Linux FTP sites, including
sunsite.unc.edu in pub/Linux/docs/HOWTO.


1.2. Disclaimer

Although this document has been put together to the best of our
knowledge it may, and probably does contain errors. Please read any
README files that are bundled with any of the various pieces of
software described in this document for more detailed and accurate
information. We will attempt to keep this document as error free as
possible.


1.3. Feedback

If you have any comments, questions or suggestions please email
them to <[e-mail]>. Definitely contact him if you find errors
or obvious omissions.


1.4. Acknowledgements

We would like to thank all the people who have contributed (directly
or indirectly) to this document. In alphabetical order:

    Andrea Dell'Amico    <[e-mail]>
    Mitchum DSouza    <[e-mail]>
    Erwin Embsen    <[e-mail]>
    Byron A Jeff    <[e-mail]>


2. NIS or NIS+ (aka. NYS) ?

The choice between NIS and NIS+ is a question of flexibility vs.
maturity.  Generally NIS has been around longer and sometimes suffers
from its age, inflexibility, and administration difficulties. NIS+
addresses all these problems, provides more flexibility, is easier to
set up and administer, and is backward compatable with NIS servers and
thus recommended for first time users setting up Linux machines within
a NIS enviroment. However, unlike NIS which is integrated into the
standard C library, NIS+ requires you to relink all deamons and clients
wishing to access these services with the NYS library libnsl.a
(similarly to SYSV - or the shared library libnsl.so). However, once
clients and deamons are compiled with NYS, they bypass the
/etc/host.conf mechanism totally (for host lookups) and determine their
resolving mechanism via the /etc/nsswitch.conf file.


3. How it works

Within a network there must be at least one machine acting as a NIS
server. If there are more machines in the network providing NIS, then
one machine is said to be the master NIS server and all the other NIS
servers are so-called slave NIS servers. Slave servers only have copies
of the NIS databases and receive these copies from the master NIS
server whenever changes are made to the master's databases.  Depending
on the number of machines in your network and the reliability of your
network, you might decide to install one or more slave servers.
Whenever a NIS server goes down or is too slow in responding to
requests, a NIS client connected to that server will try to find one
that is up or quicker.
With NYS, however, the /etc/nsswitch.conf file determines which host
you want to go to for a particular service (as there is no binding
deamon `ypbind') if your primary NIS server is not running or is too
slow to respond. This adds more flexibility as you are able to choose
on a per-service basis which host should answer what query. For
example, you may specify that if the master server `A' is down then,
for host queries, go to server `B' and for password queries go to
server `C' etc..

NIS databases are in so-called DBM format, derived from ASCII
databases.  For example, the files /etc/passwd and /etc/group can be
directly converted to DBM format using ASCII-to-DBM translation
software ('dbload', it's included with the server software). The master
NIS server should have both, the ASCII databases and the DBM databases.
Slave servers or client machines will be notified of any change to the
NIS maps, (via the "ypbind" deamon), and automatically retrieve the
necessary changes in order to synchronize their databases.


4. What you need to set up NIS?

4.1. The RPC Portmapper

To run any of the software mentioned below you will need to run the
program /usr/sbin/rpc.portmap. Some Linux distributions already have
the code in /etc/rc.d/rc.inet2 to start up this daemon.  All you have
to do is comment it out and reboot your Linux machine to activate it.

The RPC portmapper (portmap(8c)) is a server that converts TCP/IP
protocol port numbers into RPC program numbers. It must be running in
order to make RPC calls (which is what the NIS client software does).
When an RPC server is started (like a NIS server program), it will tell
portmap what port number it is listening to, and what RPC program
numbers it is prepared to serve. When a client wishes to make an RPC
call to a given program number, it will first contact portmap on the
server machine to determine the port number where RPC packets should be
sent.

Normally, standard RPC servers are started by inetd(8C), so portmap
must be started before inetd is invoked.


4.2. Determine whether you are a Server, Slave or Client.

To answer this question you have to consider two cases:

    1. Your machine is going to be part of a network with
       existing NIS servers

    2. You do not have any NIS servers in the network yet

In the first case, you only need the client programs (ypbind, ypwhich,
ypcat, yppoll, ypmatch). The most important program is ypbind. This
program must be running at all times, that is, it should always appear
in the list of processes. It's a so-called daemon process and needs to
be started from the system's startup file (eg. /etc/rc.local).
As soon as ypbind is running, your system has become a NIS client.

In the second case, if you don't have NIS servers, then you will also
need a NIS server program (usually called ypserv) and you have to
designate one of the machines in your network as a master NIS server.
Note that it is a good practise to designate at least one machine as a
slave server.


4.3. The Software

The system library "/usr/lib/libc.a" (version 4.4.2 and better) or the
shared library "/usr/lib/libc.sa" and its related DLL contain all
necessary system calls to succesfully compile the NIS client and server
software. Some people reported that NIS only works with
"/usr/lib/libc.a" version 4.5.21 and better so if you want to play it
safe don't user older libc's.  The NIS client software can be obtained
from:

  Site                   Directory                        File Name

  ftp.uni-paderborn.de   /pub/linux/yp                    yp-linux.tar.gz
  nic.funet.fi           /pub/OS/Linux/util/networking/\
                            util-swan/Programs/System/yp/ yp-linux.tar.gz
  sunsite.unc.edu        /pub/Linux/system/Network/admin  yp-clients.tar.gz

Once you obtained the software, please follow the instructions which
come with the software.


4.4. Setting up a NIS Client

Assuming you have succesfully compiled the software you are now ready
to install the software. A suitable place for the ypbind daemon is
the directory /usr/sbin.

You'll need to do this as root of course. The other binaries (ypwhich,
ypcat, yppoll, ypmatch) should go in a directory accessible by all
users, for example /usr/etc or /usr/local/bin.  It might be a good idea
to test ypbind before incorporating it in /etc/rc.d/rc.inet2.

To test ypbind do the following:

    - Make sure you have your domain name set. If it is not
      set then issue the command:

        /bin/domainname my.domain

      where my.domain is the domain your machine is part of.

    - Start up "/usr/sbin/rpc.portmap" if it is not already running.

    - Create the directory "/var/yp" if it does not exist.

    - Start up "/usr/sbin/ypbind"

    - Use the command "rpcinfo -p localhost" to check if ypbind
      was able to register its service with the portmapper. The
      rpcinfo should produce something like:

       program vers proto   port
        100000    2   tcp    111  portmapper
        100000    2   udp    111  portmapper
        100007    2   udp    637  ypbind
        100007    2   tcp    639  ypbind
        300019    1   udp    660

    - You may also run "rpcinfo -u localhost ypbind". This command
      should produce something like:

        program 100007 version 2 ready and waiting


Finally, do not forget that for host lookups you must set (or add)
"nis" to the lookup order line in your /etc/host.conf file. Please read
the manpage `resolv+.8' for more details.

At this point you should be able to use NIS client programs like ypcat,
etc...  For example, "ypcat passwd" will give you the entire NIS
password database.

IMPORTANT: If you skipped the test procedure then make sure you have set
the domain name, and created the directory:

    /var/yp

This directory MUST exist for ypbind to start up succesfully.

If the test worked you may now want to change the files /etc/rc.d/rc.M
and /etc/rc.d/rc.inet2 on your system so that ypbind will be started up
at boot time and your system will act as a NIS client. Edit the file
/etc/rc.d/rc.M and look for the commands which set the domain name.
Change the domain name into the name of your domain. Also, edit the
file /etc/rc.d/rc.inet2, comment out the lines which start up the
rpc.portmap daemon, and add the following lines just after the place
where rpc.portmap is started:

    #
    # Start the ypbind daemon
    #
    if [ -f ${NET}/ypbind -a -d /var/yp ]; then
        echo -n " ypbind"
        ${NET}/ypbind
    fi

Unlike Sun's implementation of NIS you do not need to edit /etc/passwd
and /etc/group to take advantage of NIS. Sun's implementation needs a
line "+:*:0:0:::" in /etc/passwd and a line "+:*:0:" in /etc/group to
tell NIS to search the NIS password and group databases.

Well, that's it. Reboot the machine and watch the boot messages to see
if ypbind is actually started.

IMPORTANT: Note that the netgroup feature is not yet implemented.
Netgroups allow access control for every machine and every user in
the NIS domain, and they require an entry like:

    +@this_machine_users

in /etc/passwd. At this moment, every user in the NIS password database
can access your linux machine if you run "ypbind".


5. What you need to set up NYS?

5.1 Determine whether you are a Server, Slave or Client.

To answer this question you have to consider two cases:

    1. Your machine is going to be part of a network with
       existing NIS servers

    2. You do not have any NIS servers in the network yet

In the first case, you only need to relink all client and deamon
programs with the NYS library libnsl.so (or statically link them with
libnsl.a). This means adding the line

    LIBS=-lnsl

to your Makefile signifing you want to link the Network Services
Library.

Basically all network deamons and the `login' program need to be
recompiled.  In no way is this an easy task, and a full "NYS aware"
suite of programs is being gathered.

Similarly like in the case of the standard NIS, if you don't have NIS
servers, then you will also need a NIS server program (usually called
ypserv) and you have to designate one of the machines in your network
as a master NIS server. Again, you might want to set up at least one
slave server as well.


5.2 The Software

You need to retrieve and compile the NYS services library libnsl.so.
If you don't have the DLL tools installed you may retrieve a
precompiled shared, static and stub library from the same site
mentioned below.

The NYS library (source and precompiled version)  can be obtained from:

  Site                   Directory                         File Name

  nic.funet.fi           /pub/OS/Linux/BETA/NYS            nys-0.26.tar.gz
  nic.funet.fi           /pub/OS/Linux/BETA/NYS/lib        libnsl.so.1.0.a26

Precompiled `login' and `su' programs may also be fetched from

  Site                   Directory                         File Name

  nic.funet.fi           /pub/OS/Linux/BETA/NYS/bin        login
  nic.funet.fi           /pub/OS/Linux/BETA/NYS/bin        su

Similarly, example configuration files may be retrieved from

  Site                   Directory                         File Name

  nic.funet.fi           /pub/OS/Linux/BETA/NYS/etc        *conf

For compilation of the nsl library, please follow the instructions
which come with the software. If you wish to compile the shared DLL
library you must have the DLL tools installed in the standard place
(/usr/dll). The DLL tools (the package tools-2.11.tar.gz) can be
obtained from many sites.


5.3. Setting up a NYS Client

Unlike NIS, there is no setting up required for a NYS client. All that
is required is that the configuration files (/etc/yp.conf,
/etc/nis.conf) point to the correct servers for their information. See
the examples provided with the source code.


5.4. The nsswitch.conf File

The Network Services switch file /etc/nsswitch.conf determines the
order of lookups performed when a certain piece of information is
requested, just like the /etc/host.conf file which determines the way
host lookups are performed. Again, look at at the example file provided
in the source distribution. For example, the line

    hosts: files nis dns

specifies that host lookup functions should first look in the local
/etc/hosts file, followed by a NIS lookup and finally thru the domain
name service (/etc/resolv.conf and named), at which point if no match
is found an error is returned.


6. Setting up a NYS Server

The NIS/NYS server software can be found on:

  Site                   Directory                         File Name

  ftp.lysator.liu.se    /pub/NYS                           ypserv-0.5.tar.gz
  ftp.univie.ac.at      /unix/system/linux/funet/BETA/NYS  ypserv-0.5.tar.gz
  mcsun.eu.net          /os/linux/BETA/NYS                 ypserv-0.5.tar.gz

The server setup is the same for both NIS and NYS.

Compile the software to generate the 'ypserv', 'dbcat' and 'dbload'
programs.  Firstly, determine what files you require to be available
via NIS/NYS and then add or remove the appropriate entries to the
ypMakefile. Now build the DBM files by

    % make -f ypMakefile

Make sure the portmapper (rpc.portmap) is running, and start the
server 'ypserv'. The command

    % rpcinfo -u localhost ypserv

should output something like

    program 100004 version 2 ready and waiting

That's it, your server is up and running.


7. Verifying the NIS/NYS Installation

If everything is fine (as it should be), you should be able to verify
your installation with a few simple commands. Assuming, for example,
your passwd file is being supplied by NIS/NYS, the command

    % ypcat passwd

should give you the contents of your NIS passwd file. The command

    % ypmatch userid passwd

(where userid is the login name of an arbitrary user) should give you
the user's entry in the NIS passwd file. The 'ypcat' and 'ypmatch'
programs should be included with your distribution of NIS or NYS.


8. Common Problems and Troubleshooting NIS

Here are some common problems reported by various users:

    1) The libraries for 4.5.19 are broken. NIS won't work with it.

    2) If you upgrade the libraries from 4.5.19 to 4.5.24 then the
       su command breaks. You need to get the su command from the
       slackware 1.2.0 distribution. Incidentally that's where you
       can get the updated libraries.

    3) You could run into trouble with NIS and DNS on the same machine.
       My DNS server occasionally will not bring up NIS. Haven't yet
       tracked down why.

    4) When a NIS server goes down and comes up again ypbind starts
       complaining with messages like:

         yp_match: clnt_call:
                     RPC: Unable to receive; errno = Connection refused

       and logins are refused for those who are registered in the
       NIS database. Try to login as root and if you succeed, then kill
       ypbind and start it up again.


9. Frequently Asked Questions

Most of your questions should be answered by now. If there are still
questions unanswered you might want to post a message to

    comp.os.linux.help

or contact one of the authors of this HOWTO.